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LARKEN SEQUENTIAL/RANDOM ACCESS FILE UTILITY 


The sequential/random access file utility, is a ram-resident extension to the 
eprom-based LKdos disk operating system. It allows the LKdos-2068 to handie large data 
base files and lets the user use a number of new features of the 2068 that have been 
unused previosly. Up to 4 files can be accessed at once to allow data to be sorted or 
merged etc. i 

Built into every 2068 is the basic capability to use up to 15 ‘devices’ for data 
input and output. The different devices are connected (in software) though the 2068's 
channels. The main devices used for 2068 output are the upper screen, lower screen, 
and the printer. The main input device is the keyboard. 

The commands PRINT, INPUT and INKEY# are used to send and get, data from these (or 
any other) devices. These commands in their plain form default to the commonly used 
channels eg: 


Command Default—-Channel description 


PRINT #2 Send output to upper screen 
LPRINT #3 Send output to 2040 printer 
INPUT #0 : Input data from Keyboard and can 

also print to Lower screen (Ch#0) 
INKEYS #0 Read from Keyboard 


All these commands can be directed to other channels by using a channel identifier 
after the command. Eg PRINT #0;"DATA" will send "DATA" to the lower screen, or PRINT 
#3;"DATA" will send data to the printer. INPUT# and INKEY$# can also be used to read 
data from channels other than the keyboard (ChO). 


The LKS/R (Larken Sequential/ Random access utility) allows you to send data or read 
data from the diskdrive using PRINT#, INPUT# or INKEYS#. The command syntax for 
INPUT#, PRINT#, and INKEY$# is the same for the regular INPUT, PRINT, and INKEY#. 


LOADING the RANDOM ACCESS/ SEQUENTIAL UTILITY 3 

Insert the supplied disk into the drive and RAND. USR 100: LOAD “SRcode.Bi” This 
loads the operating code in as a large Rem statement. Type RUN to initialize the basic 
memory map. (this moves the start of basic pointer up past the REM statement so it 
becomes invisible to the program) 


aR, 


THE QPEN# COMMAND 

Before you can use these commands to access a file on disk, you must use the OFEN# 
command to create a file on the disk {or re-open an existing file). The OPFEN# command 
also puts a pointer in the S048 streams table (used to point the 2048 to the channel) 
so the PRINT# and INFUT# commands see the channel as open. 

(Note the LES/R uses the same type of command structure as LKdos. LES/R commands are 
preceded by [RAND USR 246800:] (the LES/R is resident in ram just below {prog). Do not 
confuse the PRINTS and INPUT# commends used here with the PRINT#4: (LEdos command 
prefix) used for LEdas disk/ exbasic.) : 


The PRINTS, INFUT# and INEEYS# commands which are used to send and read data from a 
file are NOT preceeded by a LEDOQS RAND USR prefix. 


The LE-S/R uses the Open# command in Z modes. Output mode and Random access mode. The 
syntax is: 
O [RAND USR 26800: OPEN # ch,"filename",OUT] output type 
or [RAND USR 26800: OFEN # ch,"filename",RNDJ random type 
{QUT and RND are tokens on the "O" and "T" keys) 
tch is the channel # 2 to 15 ) 


-OUTPUT type is used to first create a file or to add more data to an existing file. 
It can only be PRINT to and cannot be INPUT from. Trying to read from an output type 
file will result in an error message. If the file already exists, the file data 
pointer (internal in LES/FE} will be set to add new data to the end of the existing 
data. 2 


-RANDOM type is used for existing files to PRINT or INPUT (or INKEY#) data from. Data 
can be read sequentially from the start of the file to end, or using the [PRINT#ch;TAB 
recordnumbers] command, data can be randomly accessed from anywhere in the file and 
read or changed. In random mode, the file cannot be lengthened. When a file is opened 
as RND type, the file data pointer will be set to the start of the file, so the first 
data accessed will be the first data in the file. 


EL NSE COMMAND See ee E ee 

After you are done accessing data from a file you must ‘close’ the file using the 
CRAND USE 26800: CLOSE #ch] command. This makes sure @11 data is sent to the disk and 
disconnects the stream from the channel so data cant be read or sent. 


Here is an example program that Opens a file as ‘output’, sends data to the file then 
‘clases’ the file. 


10 REM Create file program 

20 RAND USR 26800: OPEN #7,"Test” QUT 
30 FOR a=1 TO 10 : 

40 PRINT #75"This is record # "sa 

530 NEXT a : 
S0 REND USR 26800: CLOSE #7 


Running this program will create a file on the disk. Use the [RAND USR 100: PRINT 
"Test"] command in LEdos to see the contents of the file. 


The next example program will read the file back a ‘record’ at a time using the INFUT# 
command. The file is opened as random type. 


10 REM read file records : 

20 RAND USR 26800: OPEN #7,"Test",RND 

30 INFUT #7: a3; 

40 PAUSE &0 ¿delay to show records are read in 1 at a time 
SO PRINT af : 

60 GOTO 30 


You will have noticed that the 2068 produces a noise when using the INPUT# command. 

(This is just a small bug in the 20468 rom left over from the keyscan routine). 

The End of File error is produced when a file is read right to the very end . Even 
though the file is at the end the file is still open. You can move the ‘file pointer’ 
to the start of the file by using the command [ PRINT #7;TAR O:] (described later on) 
; OF you can close the file and re-open it. 

Note- An open file (output or random) must be closed before you remove the disk from 
the drive. - 
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Here is another example of reading a file, this time using the INKEY# # command. 
INKEYS reads a character at a time and doesnt produce the keyclick noise. 

Be sure to close the file from the previous program with [RAND USR 26800: CLOSE #71 
before going further. 


10 REM read file using INKEY 

20 RAND USR 26800: OPEN #7,"Test",RND 
3G LET at = INKEYS #7 

40 PRINT ad; 

50 GOTO 30 


INKEY$S is useful if you are searching for a specific character. It also can read 
characters that cause INPUT to have problems such as non ascii or control characters. 


After reading the last character of a file, the LES/R will return a Chr 226 (STOP) as 
its next character before causing a End of file error. Using INKEY$, it is possible to 
detect the ‘end of file’ before a error is caused. 


All data sent to a file with the PRINT# command is sent as ASCII characters. When you 
send numeric data such as [ PRINT #7;a,5,10 J the numbers are spelled out as ascii 
characters. These numbers can be read back using £ INPUT #7:a:b3c3 J] or the data can 
be read back as string data [ INPUT #7;a%;b3;c#; 1. The error ‘Nonsense in Rasic’ will 
occur if you try to read non numeric data with a numeric variable input command. 


FILE RECORDS : 
A record is a text string terminated by a record ‘separator’ such as a Carriage 


return (chriZ) or a comma (chr6). The INPUT# command #ill read characters until it 


reads a record separator, then will return with the entire record. (It works the same 
as if you are using the standard INPUT command with the keyboard. It only completes © 
input when you press enter. Also there are certain characters that INPUT doesnt like 
such as quotes “"".) 


Sequential Files 
Ordinary sequential files can™use different length records within the same file. This 


type of file works good for data that doesnt need to be changed or updated such as a - 


spell checker dictionary file, or a data base of history etc. But variable length 
records are not very useful for a file or data base that needs to modify or update its 
records because the start of a record cant be calculated because its position varies. 


Random Access Files 
For true random access operation, the length of records should be the same for all 
records. This way records can be easily replaced and modified and files can be indexed 


for fast operations. To keep all records the same length, you just need to use a DIM 


array for sending data to the file. Data can be entered into the dimensioned array and 
the same array is always PRINTed to the file. / 


To tell LKS/R the length of the file records (only needed when using the TAB and 
search commands) we use the DATA command. : 
eg: [RAND USR 26600: DATA ch, recordlength}]"” 
(ch=channel number) 
Record lengths can be up to 2K long but lengths of 32,644,128 or 256 are more common. 


FRINT# and INPUT# COMMAND STRUCTURE 
Care must be taken when using these commands not to send unwanted characters to the 
file. Always add a semicolan to the end of PRINT commands unless you want a record 
separator sent. 

INPUT commands can send data to a channel as well as read from it. For example in the 
command [INPUT “Enter Name"sa%] the input command first sends the text “Enter Name" 
to the channel, then reads in af , then sends a final chr 13 because there isnt a 
semicolan after a$. 


The correct syntax for INFUTing from a file is[INPUT #ch;a$;1 (where ch is the 
channel #). 

The INEUT# command has the same problem as the standard input command if quotes ae 
are entered as the data. Because of this the [INPUT #ch; LINE a$;1 command works 


‘better at reading data that has quotes in it. 


Multiple inputs can be done in one command with [INPUT #ch; LINE a$; LINE b#; LINE 
ef:) ete. 
The LINE type input cant be used for inputing numeric variables. 


> 


Records can be separated o carriage returns, apostrophies {') or commas. eg: 
[PRINT #ch; "Recordi" , "Recordz" © "Records"j 


STRING SESRCHING Z 

Another variation of the DATA command is used as a search command to find a specific 
text string. : 
eg: [LET x= USR 24890: DATA ch, recordlength, “word to find"] 

This command will search from the current file position to the end of the file 
locking for an occurance of the text to be found. If a match is found, x will be the 
number of records that the command had to search through to find the match. (Its the 
relative number of records from the initial position, not the absolute record number.) 
To get the absolute record number, add the initial position to the returned value x. 

The search command can be repeated to find the next occurances of the text string. 

Tf a match isnt found x will be 45535. The search command can only be used in random 
mode (RND). This command runs much faster than an equivilent BASIC routine. 


PRINT TAB COMMAND 

Atter the record length has been set, the command PRINT #ch;TAB recordnumber; 

command can be used to randomly access any record in the file. The file pointer is 
set at the start of the record, so the next record read or written will be that 
record. [PRINT #ch:TAB 0;] is an easy way to reset the pointer to the start of a file. 

Resure ta include the semicolan at the end of the TAR command or a chr 13 will be 
sent to the file. : 

The T&R function allows for true random access filing, this is something usually only 
found on very expensive computers. Using the tab function and fixed length records, 
records can be updated and modified, and specifing record lengths of 1/2 or 1/4 of the 
actual record length, parts of a record can be pointed to directly. 

If you try at access a record number that doesnt exist in the file, a ‘Number to Big’ 
error will occur. 


THE LIST COMMAND 

The command [RAND USR 26802: LIST] has been added for diagnostic purposes to let 
you see the what files and channels are currently open. The number in brackets on the 
far left of the screen is the buffer number. Buffer 1 is closest to the top of ram and 
they decend downward SE per buffer as each is opened. The LKS/R will always try to use 
free buffers closest to the top of memory when a file is opened. o 


BUFFERS and MEMORY USAGE o os 

The LES/R code loads in as a large REM statement then moves the system variable 
‘Prog’ (22435) to point to the end of the rem statement. This makes the code invisible 
to basic and safe from everything exept a NEW command. The length of the code is aprox 
2500 bytes. The entry point for commands is 24800. eg: [RAND USR 26800: OPEN 
#5,"file" ,QUT] 

he LES/R uses a SK (8100 bytes) buffer for each file open. These start at the top of 
ram above ramtop and decend downward SK for each additional file opened. When a file 
is opened, the LES/R will use the first available buffer closest to top of memory. 

The system variable (23732) P-RAMT (minus 254 bytes for udg’s) is used to find where 
the top of ram is, so if you need some memory reserved at ramtop for MC routines etc, 
you can poke (23722) down lower to preserve high ram. Do this before opening any 
files. 

You will need to move ramtop down with a CLEAR x command depending on haw many files 
you have open at once. When the LES/R is loaded, it clears ramtop down low enough for 
= files to be opened. 

To calculate what value you should clear for the maximum number of files that you 
will have open at once, 

use E P-RAMT-256 -(5100 * Number of files open) 1. 


It may seem that 5K per buffer is a lot of memory to give up, but considering how 
much data that buffer will allow the 2048 to access (up to 800K) its not that bad a 
comprimise. 


CONFIGURING your PROGRAM to AUTO RUN 

To use the LKS/R code with your Programs you need to have the "SRcode.Bi" load in and 
after it initializes it should then load in your program. This is easily done by 
adding a line after the initialize lines to load in your program. Then save the Rem 
code to auto run at line 10. 

See the LBEASE.BC program for an example. 
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NOTES ON USING RANDOM ACCESS/ SEQUENTIAL FILES 
L Be sure not to remove a disk from a drive that has a file open. If a disk is 
switched in a drive that has a file open, files on the disk will be corrupted ! 
- When using multiple drives, select the drive with the GOTO command in Lkdos before 
using the OPEN command. The LKS/R will remember the drive number after that for all 
file accesses. ; : 
- Besure not to accidently use the RAND USR 100:CLOSE ch instead of RAND USR 24800: 
CLOSE ch . The file will appear to be closed but really isnt. If you arnt sure do a 
RAND USR 26800:CLOSE ch also. : 
- PAPER, INK and other attribute commands need to be used with care so not to corrupt 
files. These commands will send attribute control bytes to the last stream open. So 
the following lines: 10 INPUT #7;a%; es 

20 PAPER ü 

will send the paper 0 control bytes to stream #7 which will corrupt the file. This can 
be avoided by using a PRINT 3; command before the attribute command to make the screen 
the last stream open. eg: 20 PRINT 3: PAPER 0 
- The ONERROR command can be used to detect ‘End of File’ and ‘Number to Big’ t Tab 
command) errors, but new error messages included in the LES/R will cause the program 
to stop. : 
= Disks should have their write protects removed while a file is open. Random type 
files should have the write protect removed normally, but it can actually be used » 
with the sticker on the disk however no data will be changed on the disk. 
- The LEdos Version 3 eprom has sequential file commands built into it. There may be 
some problems using the eprom sequential file commands in conjuntion with the LKS/R. 
This is because the Eprom based filer keeps the-file in the Lkdos cartridge ram buffer 
as it is reading or writing to it. The LKS/R may at any time need a disk access which 
will wipe out any data that is in the LKdos cartridge ram buffer. The LES/R doesnt 
recognise the ‘File Open’ condition that is in the V3 eprom. This is because LKS/R is 
designed to be used with any version including older versions of LKdos that dont have 
the File Open condition. 
- Files up to 800K can be created ( One file can occupy a full disk) however if a file 
is greater than 50 blocks long (aprox 250K) the directory entry that keeps track of 
the list of blocks will become so big that it will start to overwrite the next file 
name in the directory. So if you plan to have a huge data file that large or larger, 
either keep it on a disk that doesnt have other files, or after creating the file, 
save dummy file names to the next- few directory entrys te reserve them, Or- using the 
disk editor,enlarge the data files directory entry to the max size you will need. 


#* LBASE , An Example Data Base ** 

On the disk is a simple data base manager program that 1 have added to help 
demonstrate an application of random access files. I have also included a data base of 
TIME DESIGNS magazine articles, news and reviews etc . The magazines date from Jan 
1986 to Sept 19788. 


To load LBASE, type RAND USR 100: LOAD “LBASE.BC" This will load the LKS/R code 
which will initialize its self and then load LBASE.B1 . 

The main menu should appear on the screen. Type "OG" to open a file. Enter the drive 
#, then the file name ‘TIMEDESGN’. The file will be opened {as RND) at the first 
record. 

Pressing ‘R’ will read the next record, ʻE’ will let you edit the record,’A’ will let 
you add records, ‘S’ will search for a word(s) from the record you are at to the end 
of the file and ‘C’ will close the file. You can create a new data base with the ‘N’ 
command. {not on the master disk though) 

Each record on the file is 254 bytes long. The noise you hear is the input command 
reading in 256 bytes. 

This program is only a very small example of what the random access files can do and 
-is in no way complete. You could expand it do do many other things. 


- About the Lbase program : 

Break the program and Llist it to a large printer or just list it on the screen to 
examine it. It isnt very long, and most of it is the mini text editor and to print the 
MENUS. 

Key points of the program are: d$ (2546) is the array used for sending and reading 
data from channel #7 which is the channel used for the file. 

The record length set by the DATA command is 257 because the record separator makes 
up the extra character. 

The variable CH7 is set to 1 if channel 7 is open and set to 0 channel 7 is closed. 
If other channels were open as well, you could use similar variables to keep track of 
their status as well. 

SPDOS is used instead of 26800 to make the listing more clear. 

The Gnerror command is used to detect the end of the file. If it occurs, the file 
pointer is set to the beginning with the TAB 0; command. 5 


ADDING NEW FEATURES TO LBASE. : Ve 

There are many improvements that could be added to LRBASE. A comercial data base 
program such as D-Base for the IBM PC uses a index file as well as the main data file. 
The large data file isnt in any perticular order. The index file contains the record 
order that the data file should be read. If you want to for example put the data base 
in alphabetical order, D-Base would read the entire data file thought once and create 
a new index file accordingly. This way sorts can be done much faster. 

Lbase could have Z or more files open at once so records could be sorted to other 
files. This is an other way of sorting the data base. 

Records can be inserted in the middle of a file using 2 files. Open a new file as 
output. Send a certain number of records to the new file, then send the inserted 
record or a blank record, then send the rest of the ald file to the new file. 

Lbase uses an unfielded record and data is just entered in free form. Data fields 
could be added if required. a 

A more elaberate search command could be added (like the one in Frofile) using AND 
and GR functions to do inclusive or exclusive searches. This could be done in MC or 
compiled Basic to improve speed. 


COPYING FILES - 

Copying files is very easy in basic although it may take some time. Here is an 
example: 3 

10 RAND USR 26800: OPEN #4,"Scource", RND- 

20 RAND USR 26800: OFEN #7,"Target", OUT 

Z0 INPUT #6; LINE at; :PRINT #7;af 

40 BITO 30 

Atter the end of file error occurs, Close the files. You could use ON ERROR to auto 
close the files. 

A similar copy could be done using INKEY$. This would be slower but capable of 
reading some characters that cause INPUT problems. 


ACCESSING FILES FROM MACHINE CORE 
For greater speed in sorting and copying files a simple machine code routine could be 
used. The Open and Close commands have to be done in Basic though, but after files are 
opened, MC can be used. 

The rom call ‘channel select’ (1230h) can be used to set the current channel (23633 
sytem variable CUR-CHL) as the one you want to access. Call this routine with the 
accumulator holding the channel# you want. eq: The equivilent of FRINT #7; "2"; in MC 
is 


LD A,7 : Channel to use j 
CALL #1230 3 Set CUR-CHL addr to point to ch7 
LD Ay $ character you want to send 

RST 16 3 Use print char to send character 


The channel select routine (#1220) when called selects the OUTPUT routine address of 
thet channel. The input routine is 2 bytes past the output routine, so after callin 
#1230 to select the channel, cail the following routine to get a character. 

GETCHR LD HL, (23632 

INC HL 
INC HL 
LD E (HL) 
TNE HL 
Lb tn 
EX ers 
JP CHL) 

The routine will return the character in the accumulator. A chr 226 signals that you 
have read the last byte of the file, or you could let a basic On error handle the end 
of file. 

Once the address of the channels input and output routines are found using #1230 
these could be remembered by your routine so #1229 doesnt need to be called for each 
character. This would speed up the cade. 

For keeping track of records, you need to keep a counter or you could count file 
separators if you are sure they are consistant. 


COMPILED BASIC 

Basic can be compiled to really increase the speed of sorting copying and manual 
searching, How ever OFEN CLOSE and DATA commands will have to be left in regular 
basic. 


Further Assistance 

Tf you need any further information on using this software, you can call me (Larry 
Kenny 413-535-2680). 

The assembly language source file (zeus assembler) for the LKS/R is available from 
Larken Electronics (send $5). 


Technical Information on the Internal Operation 


When LES/R is loaded and initialized, the channel table is expanded by adding 4 new 
entrys for the maximum 4 files that can be open. The entrys consist of the output 
address, the input address, and a one byte device spec. 

( For more information on channels and streams, see page 100 in the 2068 technical 
manual). 


The index register is used extensivly in the code. The addresses in the file 
channels in the channel table, point to entry points in the code that just load the 
IX register with the address of the corresponding file info block, and then jump to 
the common code used for input and output for all files. 


The file info blocks consist of 26 bytes where the : file name, drive #, current 
data block, address in that block, free bytes in the block, pointer in directory of 
the block and rnd/out type are kept for the file. Using the index register is ideal 
for using common code for a number of different files at once. To find the address 
of the data block for a file, just look at the index register on exit from a call to 

the LES/R. 


When a file is opened as ouput and if it already exists, the file info block (fib) 
is set to the end of the existing data and any new data is added to the file. As 
each block gets filled, it is saved, the block # is added to the files directory 
block list in the dir cell, and the block number of a new block is fetched from the 
track map and marked at this time as used in the track map. It is marked as used 
even before its completly filled because while the file is open, we dont want any 
other file to claim it. 

When a file is open as output, an error message will occur if a read attemp is 
made. 


When a file is opened as RND, the fib is set to point to the begining of the file. 

The file can be read from or written ta, so when ever the pointers reach the end of 
a block, the block is first saved, then the next block is loaded. Saving the block 
first makes sure and data changed in the block was saved. It is the reason for most 
of the disk activity as you read a RND type file. Some disk systems have a separate 
‘input only’ file operation which runs faster. The sequential input in the V3 eprom 
is a input only so it can read a file much than the RND type in LES/R. 


Closing a file saves the block in the buffer to disk, disconnects the stream that 
points to the channel, marks in the fib file closed, and if the type is output 
enters the current block in the directory cell. 


The search command trys to speed disk searches up a bit, by after saving the 
current block to make sure no altered data is lost, it doesnt resave any other 
blocks as it searches though them. This cant be done easily from outside the code so 
external custom seaches will be a little slower. 


When the code sees a TAR character, it then reads in the next 2 bytes to get the 
record #. It multiplies the record # by the record length, and then divides this 
number by 5090 to see which block the record is in. The remainder is the address in 
that block. It then loads in that block and sets up the fib to point to the block 
and address. 


Using the Ramdisk will significantly increase the speed of file searches and file 
access. The file can be copied to the ramdisk for use and then copied back to disk 
when you are done. 

Machine code copy routines could really speed up copying. 


